@callmehiphop let me know what you think of the usability. Ready to start on tests after.

Could you throw up a gist or something of more code examples? Or is the README example all there is to it?

README + system tests is all for now. It's not a very big API, just 3 methods. I did fail to mention there's a verbose mode for each method call.

The two primary ways of calling are

// inline
language.detectEntities('a sentence', function(err, entities) {});

// with a document
var document = language.detectEntities('a sentence');
document.detectEntities(function(err, entities) {});

The verbose mode just makes less simplifications. These tests show what the general responses look like in simple/verbose mode for each annotation type (annotation, entities, sentiment): https://github.com/stephenplusplus/gcloud-node/blob/spp--language/system-test/language.js#L314

LMKIYHAQ

I see, is there a reason we only provide convenience methods for entities and sentiment? Where as your readme example shows tokens, language and sentences as well.

There are only 3 API endpoints, see https://cloud.google.com/natural-language/reference/rest/v1beta1/documents:

• analyzeEntities (detectEntities)
• analyzeSentiment (detectSentiment)
• annotateText (annotate)

We can add things like detectSentences() and detectTokens(), it would just be plucking out only part of the annotate() response. It might end up with users thinking they have to run both functions to get both types of annotations. WDYT?

We can add things like detectSentences() and detectTokens(), it would just be plucking out only part of the annotate() response.

We took this exact approach with the vision api, did we not? Granted the vision annotate() response has more data in it, convenience methods sorta seem like one of the big reasons why gcloud-node exists, no?

It might end up with users thinking they have to run both functions to get both types of annotations.

Can't this be prevented with documentation? Stating that it's a convenience method for annotate()?

We took this exact approach with the vision api, did we not?

No, the Vision API has one API method that returns a response that matches the type of request you send. So we have detectFaces, which makes a request that asks for facial detection, so the response only includes facial detections.

convenience methods sorta seem like one of the big reasons why gcloud-node exists, no?

What we're talking about here is making a request that includes a lot of info, but only returning a part of it. I can see both sides here, however this is new territory for us. I feel conflicted because we would essentially be throwing away information. Docs can help, but a user simply seeing methods called detectTokens and detectSentences will make them think these each have to be called to get those types of detections.

No, the Vision API has one API method that returns a response that matches the type of request you send. So we have detectFaces, which makes a request that asks for facial detection, so the response only includes facial detections.

Ah, my mistake. Fair enough then, feel free to ignore!

Docs preview: http://stephenplusplus.github.io/gcloud-node/#/docs/master/language

All tested and doc'd @callmehiphop. PTAL when you can.

@jmuk -- I rebased this PR against @jmdobry's modularization PR. That is still in development, but it will hopefully merge soon. You can use the new structure to get started with #1464. If the changes you make can be limited to just creating files, as opposed to amending the files in packages/language, that should make it pretty safe in regards to avoiding conflicts.

You will need to run these commands when setting up the repo:

$ ./scripts/link.sh
$ cd packages/language
$ npm install

# good to go-- helpful development commands:
$ npm run lint
$ npm run test
$ npm run system-test

@callmehiphop sorry for the huge PR now... all of the language changes for review are here: https://github.com/stephenplusplus/gcloud-node/tree/spp--language/packages/language

@jmuk @callmehiphop -- I rebased this off of master now.

Coverage remained the same at 100.0% when pulling ecfbeda on stephenplusplus:spp--language into 143f120 on GoogleCloudPlatform:master.

@callmehiphop anything left for me to do here?

@stephenplusplus I had a couple small comments, but nothing really important. I think overall it looks good, my only real complaint is that the system tests were a little tricky to work through.

Yeah, the system tests have a unique style for sure. If it gets to be impossible to deal with when adding new features/debugging, we can look into changing that.

PTAL!

Coverage remained the same at 100.0% when pulling 3be25bc on stephenplusplus:spp--language into b6433a1 on GoogleCloudPlatform:master.

Coverage remained the same at 100.0% when pulling f007c7e on stephenplusplus:spp--language into b6433a1 on GoogleCloudPlatform:master.

Coverage remained the same at 100.0% when pulling f007c7e on stephenplusplus:spp--language into b6433a1 on GoogleCloudPlatform:master.